Magnum One/Magnum One (Mid-American Digital) (Disc Manufacturing).iso/d3/ws5macro.arc/WSS.DOC

Text File | 1991-01-10 | 28KB | 736 lines

=================================================================


         WSS:  WORDSTAR SHORTHAND COMPILER AND DECOMPILER

   A Toolkit for Editing WordStar and NewWord Shorthand Macros

      With Optional Support for 25 NEW Shorthand Characters


                              * * *


                           Version 1.1

                          17 March 1988


                              * * *


            Programs Copyright 1989 by GARY M. GIBSON

                CompuServe User I.D.:  76616,3643



Documentation Copyright 1989 by ROBERT J. SAWYER and GARY M. GIBSON

                       All Rights Reserved


===================================================================




INTRODUCTION
============


     The package consists of two MS-DOS programs, WSSC.EXE and
WSSD.EXE which allow you to compile and decompile the Shorthand
macro storage files used by WordStar and NewWord.  They also
allow you to optionally use up to 25 additional Shorthand
characters besides the traditional 0 through 9 and A through Z.

     To install WSS, copy the files in this package to your
WordStar working disk or subdirectory.




SHORTHAND
=========


     The following MicroPro and Roxxolid word-processing programs
all have essentially the same limited macro facility called
"Shorthand."

          WordStar Professional Release 5.5
          WordStar Professional Release 5
          WordStar Professional Release 4
          WordStar, CP/M Edition, Release 4
          NewWord 3 MS-DOS
          NewWord 2 MS-DOS
          NewWord 2 CP/M

     These programs all store their macros in files with exactly
the same format.  For all versions of WordStar, the storage file
is called WSSHORT.OVR by default; for NewWord, it's NWSHORT.OVR.
These filenames can be changed using the appropriate installation
program (WSCHANGE for WordStar; NWCHANGE for NewWord) at menu C
(Computer), D (WordStar/NewWord's Files), or directly at
user-area label SVFILE.  If you are using WordStar 5 or greater
and you have WSEX:  The WordStar Extender (available from Library
13 of the CompuServe WordStar Forum in file WSEX.ARC), you can
also specify on the command line a Shorthand filename other than
the default by using the /FS option.

     Using the Shorthand feature of WordStar and NewWord, you can
build a WSSHORT.OVR or NWSHORT.OVR file containing up to 36
user-defined Shorthand macros.  They will be stored in
alphanumeric order from 0 through 9 and A through Z.  Using WSS,
you can add up to 25 more characters, and these, too, are stored
in the standard ASCII collating sequence.

     The file format for WSSHORT.OVR and NWSHORT.OVR, provided by
provided by Peter Mierau, principal author of WordStar 4 and 5
and all versions of NewWord, is as follows:

          Byte       Shorthand character
          Word       Size of macro description for menu (X)
          Word       Size of macro keystrokes (Y)
          X bytes    Description for menu
          Y bytes    Macro keystrokes

     All of the user-defined macros are packed together one right
after another.  They are terminated with a zero byte.  The
predefined macros (such as @ for today's date or = for the result
from the last ^QM or ^KM math calculation) are NOT stored in the
WSSHORT.OVR or NWSHORT.OVR file and may not be changed with
WordStar, NewWord, or WSS.

     Although the file format for WSSHORT.OVR or NWSHORT.OVR is
identical in all MS-DOS and CP/M versions, because of changes in
the way WordStar 5 works -- particularly its use of dialogue
boxes -- some macros created under WordStar 4 or NewWord will
require editing before they will execute properly under
WordStar 5.




WSSD and WSSC
=============


     WordStar and NewWord do allow you to create and edit macros
in the Shorthand dialogue box.  However, editing is extremely
limited:  cursor movements are confined to the basic one-key
editing diamond (no ^Q commands), typing is always in insert
mode, and no block commands are allowed.  Also, macros that are
longer than the "Definition?" field in the dialogue box are very
awkward to deal with, requiring you to enter the last part of the
macro first, then cursor back to the beginning of field and enter
the first part.  Further, WordStar and NewWord will ONLY allow
you to edit the 36 officially-sanctioned user-defined Shorthand
characters.  You must use WSS to edit the additional 25 Shorthand
characters if you choose to use them.

     WSSD is the WordStar Shorthand Decompiler.  It will scan
your WSSHORT.OVR or NWSHORT.OVR file and produce a plain ASCII
text file containing your Shorthand macros in a format you can
edit easily with WordStar's or NewWord's non-document mode (or
another ASCII editor).

     WSSC is the WordStar Shorthand Compiler.  It will take the
ASCII file after you've finished editing it and make a new
WSSHORT.OVR or NWSHORT.OVR file from it.




COMMAND-LINE SWITCHES
=====================


     WSSC accepts a number of command line options which may
appear anywhere on the line, separated from each other and from
file specifications by one or more blanks.  Each option must
start with a slash (/) or hyphen (-).  The options are all
switches.  An option switch is set by specifying the option
itself or with a trailing plus sign (+).  The option switch is
cleared by a trailing hyphen (-).

     Options are identified by the letter following the slash or
dash; letter case doesn't matter.  Any number of letters and/or
digits may appear after the letter, if desired, to make a more
meaningful option name.  You can use these command-line switches
in batch files, if you like.


The WSSC command-line switches are:

/A[+|-]        Additional Shorthand characters allowed, meaning
               you can use up to 25 new Shorthand characters, as
               discussed below, for a total of 61 Shorthand
               character.  Default is /A- (off), which means you
               can only use the 36 characters 0 through 9 and A
               through Z.  If an additional character is used as
               a Shorthand macro name and the /A option has not
               been specified (or it has been disabled via /A-),
               an error message is given and no compiled
               Shorthand file will be produced.

/Q[+|-]        Quiet mode. Default is /Q- (off).  If the /Quiet
               option is not specified, WSSC displays
               informational messages at the end of a successful
               compilation.  If this option is turned on, WSSC
               minimizes the number of informational messages it
               generates during and after the compilation
               process.

/W[+|-]        Warning messages displayed.  Default is /W+ (on).
               If this option is turned off, WSSC will only
               display error messages, never warnings.  If it is
               on, each additional Shorthand character definition
               will produce a warning message, but compilation
               will proceed.




ADDITIONAL SHORTHAND CHARACTERS
===============================


     WSS allows you to define up to 25 additional Shorthand
characters.  To compile them, you must use the /A+ WSSC
command-line switch discussed above.

     Starting at the upper left of a 101-key keyboard and moving
to the lower right, these characters are:

Unshifted:          `      open single quote
characters:         -      hyphen (or minus)
                    [      left square bracket
                    ]      right square bracket
                    \      backslash
                    '      apostrophe (or close single quote)
                    ,      comma
                    .      period
                    /      slash

Shifted             ~      tilde
characters:         %      percent
                    ^      caret
                    &      ampersand
                    (      left parenthesis
                    )      right parenthesis
                    _      underscore
                    {      left brace
                    }      right brace
                    |      pipe (or vertical line)
                    :      colon
                    "      double quote (or inch)
                    <      less than (or left angle bracket)
                    >      greater than (or right angle bracket)

Numeric-keypad      *      asterisk
characters:         +      plus

(For the numeric-keypad characters, you can also use the shifted
version:  Shift-8 for asterisk and Shift-= for plus.)

     Note that these additional Shorthand characters are not
supported by MicroPro or Roxxolid.  They function correctly in
all WordStar 4 and 5 releases and in NewWord 3, but they may not
work with future versions of WordStar.  Given that MicroPro
already uses several characters (including @, #, and =) to
designate special built-in Shorthand macro functions, some of the
25 additional characters may become unavailable for redefining in
WordStar releases.

     Note, too, that although you can execute the defined
functions in WordStar or NewWord, you CANNOT define or change the
definitions for these characters with those programs.  You must
define them in a WSSC-compatible ASCII file, as described below.

     If you are using a 25-line screen, the WordStar or NewWord
Shorthand Menu, which lists the names of defined Shorthand
characters, can only show a maximum of 45 macro names (three
columns of 15 names), despite the fact that a total of 61 may now
be defined via WSS.  If you are using at least a 31-line screen
display (perhaps with an EGA, VGA, or, with WSEX, Hercules
RamFont card), you will see all the macro names.

     With any screen dimensions, you can always scroll through
the whole list on the Shorthand definition screen:  Issue <Esc>?
to bring up that screen, and then scroll the display with ^Z and
^W.  Remember, though, you can only view the additional Shorthand
characters from this display -- you cannot use it to change their
definitions.




USING WSS
=========


     The best way to learn these program is to try them.  If you
want to perform major surgery on your Shorthand overlay file
WSSHORT.OVR, enter this command at the system prompt:

          WSSD wsshort

     WSSHORT.OVR must be in the current directory.  WSSD will
produce an ASCII file, WSSHORT.SHD, which you can edit in
non-document mode, a process described in detail below.  When you
have the macros the way you want them to be, you can compile the
*.SHD file back into a Shorthand overlay compatible with WordStar
or NewWord by issuing this command:

          WSSC wsshort

     Note:  This will overwrite the old WSSHORT.OVR with the new.
To avoid this, both WSSC and WSSD allow a second filename, with
optional extension, to designate the output file.  So if you
enter:

          WSSC wsshort updated

WSSC will create UPDATED.OVR.  You can test the macros in
UPDATED.OVR by using WSEX's /FS switch, or by using WSCHANGE or
NWCHANGE to change the default Shorthand filename to UPDATED.OVR.

     In summary, the command-line formats are:

To decompile:

          WSSD [switches] shrthand[.OVR] [source[.SHD]]

To compile:

          WSSC [switches] source[.SHD] [shrthand.OVR]]

Information in square brackets is optional.




EDITING A DECOMPILED SHORTHAND OVERLAY
======================================


     A decompiled Shorthand file (*.SHD) is an ASCII text file
containing two lines for each Shorthand macro you have defined.
(Actually, you don't have to work on a decompiled Shorthand file.
As long as you adhere to the format described here, you can build
your *.SHD from scratch in WordStar or NewWord's non-document
mode.)

     The lines in a decompiled Shorthand file should have the
following format:

Line 1:   Shorthand-character  Shorthand-description
Line 2:                        Shorthand-definition

     The lines are shown here indented (as created by WSSD) but
any number (including zero) of blanks or horizontal tabs
(ASCII HT) may precede or follow any item.


The components of a definition line pair are as follows:

Shorthand-character     A valid WordStar or NewWord Shorthand
                        definition character (0-9, A-Z) in
                        uppercase or lowercase, or one of the 25
                        WSS additional Shorthand characters.
                        This is required.

Shorthand-description   Optional text to describe the use of the
                        macro.  Begins with the first non-blank/
                        non-Tab after the Shorthand-character and
                        ends with the last non-blank/non-Tab on
                        the line.  May be blank.  See below for
                        the details on character coding.

Shorthand-definition    Optional text defining the macro.  If
                        present, the text *must* be enclosed in
                        quotation marks ("----").  To make a null
                        definition, so the macro will appear on
                        the Shorthand menu without doing
                        anything, simply put two consecutive
                        quotation marks on this line:  "".


     The Shorthand-description and Shorthand-definition text may
contain any printable ASCII character.  If you enter a character
from the IBM extended character set, either with WordStar or
another editor, WSSC will compile it properly.  However,
decompiled files produced by WSSD will show extended characters
as their low-order ASCII equivalent.  (Version 1.0 of WSSD placed
^[ and ^\ (caret, left square bracket; caret, backslash) fences
around the decompiled extended characters.  Recompiling this
format with WSSC is still supported, so you can use your .SHD
files created with WSS 1.0 without alteration.)


     The following character pairs must be used to enter certain
characters:

        ^c      Any valid control character in standard ASCII
                notation typed as a caret (^) followed by the
                character:  ^A through ^Z in either uppercase or
                lowercase, or ^@, ^[, ^\, ^], ^^, or ^_.  Note
                that to enter the character WordStar and NewWord
                call ^6, you must type it as two carets, ^^.

        \^      Forces a caret (^) character to be included.

        \"      Forces a quote (") character to be included.
                This is not really necessary for the
                Shorthand-description, but it is supported there
                as well for consistency.

        \\      Forces a backslash (\) character to be included.

     You can put any number of blank line or comment lines
between definition pairs.  However, comment lines must begin with
semicolon (;) characters, like this:

; this is a comment line.

(It's because we use the semicolon this way that WSS does not
allow it as a Shorthand character.)

     When WSSD creates a file, it automatically adds comment
lines at the top identifying the filename and date and time of
creation of the *.OVR file it decompiled.  For example:

; Decompilation of WordStar Shorthand file C:\WS5\WSSHORT.OVR
; Shorthand overlay file was created on 17 Mar 1989 at 5:00pm

Feel free to edit or delete these lines if you like.

     No WSSC source input lines can exceed 255 characters in
length.  Warning:  if you exceed this length, the line is
truncated WITHOUT an error message being produced.  Note, too,
that the longest Shorthand-description that will fit in the
Shorthand Menu display without possibly overwriting another
description is 22 characters.  (By the way, WSSD has no intrinsic
output line length, so it can create lines longer than WSSC can
handle on input.  However, this would only occur if a Shorthand
macro's description or definition text was very long indeed.)

     Normally, Shorthand definitions are stored in
alphanumeric/ASCII-collating  order, but you may have changed
some of the Shorthand-character assignments with DEBUG or a
similar tool (previously, the only way to rename a Shorthand
macro).  This causes them to be stored out of order.  The
decompiler, WSSD, compensates for this and always decompiles the
definitions in alphanumeric/ASCII-collating order.

     However, the compiler, WSSC, will accept definitions in ANY
order.  This means you don't have to worry about maintaining the
alphabetical sequence and you can group definitions by function
in the *.SHD file for easy reading.  If you happen to define the
same Shorthand-character twice, the first definition is the one
that is used.  When WSSC is run, it will inform you of what has
happened with a diagnostic message.  If you have a formatting
error in your edited file, WSSC will not produce a new Shorthand
overlay.  Instead, it will terminate with an error message.

     WSSC produces files that can be substantially smaller than
those saved by WordStar or NewWord.  Those programs sometimes
save more than they need; WSSC never does (they will always save
the number of 128-bytes records specified at HANMAX, described
below, even if all that space has not been used).  When compiling
is finished, WSSC displays the name of the output (*.OVR) file
and its size in bytes.



MEMORY BUFFER FOR SHORTHAND CHARACTERS
======================================

     When WordStar or NewWord is run, the macro storage file is
loaded into a fixed-length buffer in RAM.  If there isn't enough
memory, it truncates to the last macro that will fit.  The buffer
size can be changed with WSCHANGE or NWCHANGE at menu C
(Computer), C (Memory usage), or directly at user-area label
HANMAX (ShortHANd MAXimum file size).  HANMAX is sized in records
of 128 bytes, so a value of 4 sets aside 512 bytes.  Note that
each defined Shorthand character takes up five bytes plus the
number of characters in the description and definition lines.  If
you set HANMAX to zero, Shorthand is disabled and the <Esc> key
will clear the screen instead of initiating the macro function.
Note, too, that the Shorthand buffer is a subset of the editing
buffer -- the more space you set aside for macros, the less space
is available in RAM for holding your document before it spills
over to disk.

     Unless you have specified the /Quiet option, WSSC will tell
you how big a HANMAX setting you will require by displaying a
message such as this after a successful compilation:

      WordStar Shorthand Compiler - Version 1.1
      Copyright (C) 1989 by G Systems.  All rights reserved.

      Your new C:\WS5\WSSHORT.OVR file is 315 bytes long.
      A minimum HANMAX setting of 3 is required to use it.

      With HANMAX set to that value, you will have 69 bytes free.
      The HANMAX value can be changed at WSCHANGE menu C,C.


     If you use WSEX:  The WordStar Extender, version 1.1, to be
available in Library 13 of the CompuServe WordStar Forum as soon
as WordStar 5.5 is made public, this fixed-length RAM buffer will
be sized automatically each time you run WordStar to accommodate
whatever Shorthand file you try to load.




THE SAMPLE FILES
================


     Included in this package are two sample compiled Shorthand
storage files, 36.OVR and 61.OVR.  They can, of course, be
decompiled with WSSD.

     36.OVR contains the same definitions provided in the
WSSHORT.OVR file distributed with WordStar 5.0.  All the other
regular Shorthand characters are defined as null values, for a
total of 36 macros.

     61.OVR also contains the same definitions provided in the
WSSHORT.OVR file distributed with WordStar 5.0.  All the other
regular Shorthand characters and the 25 additional Shorthand
characters are defined with null values, for a total of 61
macros.

     What good are 36.OVR and 61.OVR, you may ask?  Well, suppose
you aren't using any of the 25 additional Shorthand characters,
and you have defined 28 of the 36 available Shorthand characters.
Your Shorthand menu might look like this:

 0 Previous Page          1 Next Page              2 Date & Time
 3 Sans-Serif 10          4 Roman 10               5 Courier 10
 6 Soften Return          8 Erase to EOF           A Sort Ascending
 B Import Box             C Center                 D Sort Descending
 F Show All Files         G Go To Any Note         H Letterhead
 I Insert Five Spaces     J Open Journal           K Kill *.BAK
 L Log to Root Dir        M Memo                   N Novel
 P Previous Paragraph     R Reformat From Top      S Sincerely
 T Transpose Word         V Center Vertically      Y ^P-Yellow
 Z Zubenelgenubi

     Quickly now:  which characters are currently undefined?
Hard to tell, right?  But if the undefined characters have null
definitions, your Shorthand menu would look like this:

 0 Previous Page          1 Next Page              2 Date & Time
 3 Sans-Serif 10          4 Roman 10               5 Courier 10
 6 Soften Return          7                        8 Erase to EOF
 9                        A Sort Ascending         B Import Box
 C Center                 D Sort Descending        E
 F Show All Files         G Go To Any Note         H Letterhead
 I Insert Five Spaces     J Open Journal           K Kill *.BAK
 L Log to Root Dir        M Memo                   N Novel
 O                        P Previous Paragraph     Q
 R Reformat From Top      S Sincerely              T Transpose Word
 U                        V Center Vertically      W
 X                        Y ^P-Yellow              Z Zubenelgenubi

     You can see at a glance that 7, 9, E, O, Q, U, W, and X are
available.  Note, though, that defining unused characters with
null values does make the Shorthand file bigger (by five bytes
for each character with a null definition).




WSSC MESSAGES
=============


WSSC: Character "c" cannot define a Shorthand macro.

    Only the characters 0-9 and A-Z (either case) may be used to
    name Shorthand macros, or the 25 additional characters IF the
    /A switch has been used.  You attempted to define a Shorthand
    macro using another character, c.


WSSC: Compilation error(s), no output file created.

    This indicates that there was at least one Shorthand macro
    definition error during the compilation.  No output file is
    written; any previous file of the same name still exists.


WSSC: Duplicate definition of "c".

    The Shorthand macro "c" was previously defined in the input
    (*.SHD) file.  The duplicate definition is ignored -- the one
    defined first in the input file is the only one that appears
    in the output file.


WSSC: Error on line n: <text>

    The input file (*.SHD) contained an error on line 'n' which
    is described by the following message.  The line itself is
    shown as 'text'.


WSSC: Input file "filename" close error.

    The input (*.SHD) file could not be closed successfully.
    This usually indicates that memory has been corrupted in some
    way.  It may indicate a bug in WSSC.


WSSC: Input file "filename" not found.

    The input (*.SHD) file cannot be found in the current
    directory.


WSSC: Input file "filename" read error.

    An error has occurred reading the input (*.SHD) file.


WSSC: Invalid ^char sequence: ^c.

    A control character (^c) sequence had an invalid second
    character.  Only letters (either case), the special
    characters @, [, \, ], and _, or the sequence \^ may follow a
    caret.


WSSC: Last Shorthand definition is missing 2nd line.

    The input (*.SHD) file terminated after the first Shorthand
    definition line of a pair.


WSSC: Missing character after last "\".

    A Shorthand definition line ended with a backslash.  The "\"
    must be followed by at least one character.


WSSC: Missing character after last "^".

    A Shorthand definition line ended with a caret.  The "^" must
    be followed by at least one character.


WSSC: No Shorthand macros defined.

    The input (*.SHD) file contained only blank lines,
    commentary, or erroneous Shorthand macro definitions.


WSSC: Output file "filename" cannot be created.

    There are no available directory entries on disk or there is
    an existing file of the same name which has the read-only
    attribute set and cannot be overwritten.


WSSC: Output file "filename" close error.

    The output (*.OVR) file could not be closed successfully.
    This usually indicates that memory has been corrupted in some
    way.  It may indicate a bug in WSSC.  The file may or may not
    actually exist on disk.


WSSC: Output file "filename" write error; disk full?

    A write to the output (*.OVR) file was unsuccessful or
    incomplete.  A common cause of this is not having enough room
    available on the disk to which you are writing.


WSSC: Processing terminated.

    A previously described error has caused WSSC to terminate
    processing without creating a complete Shorthand overlay
    file.


WSSC: Text must be enclosed in quotes ("---").

    The definition of a Shorthand macro (on the second line of a
    definition line pair) must be enclosed in quotation marks.




WSSD MESSAGES
=============


WSSD: Input file "filename" close error.

    The input (*.SHD) file could not be closed successfully.
    This usually indicates that memory has been corrupted in some
    way. It may indicate a bug in WSSD.


WSSD: Input file "filename" is not a WordStar Shorthand file.

    The input file you specified does not appear to be a WordStar
    or NewWord Shorthand file.  Please check to ensure that you
    spelled the file's name correctly and, if so, that the file
    actually is recognized by WordStar as a Shorthand definition
    file.


WSSD: Input file "filename" not found.

    The input (*.OVR) file cannot be found in the current
    directory.


WSSD: Input file "filename" read error.

    An error has occurred reading the input (*.OVR) file.


WSSD: Output file "filename" cannot be created.

    There are no available directory entries on disk or there is
    an existing file of the same name which has the read-only
    attribute set and cannot be overwritten.


WSSD: Output file "filename" close error.

    The output (*.SHD) file could not be closed successfully.
    This usually indicates that memory has been corrupted in some
    way.  It may indicate a bug in WSSD.  The file may or may not
    actually exist on disk.


WSSD: Output file "filename" write error; disk full?

    A write to the output (*.SHD) file was unsuccessful or
    incomplete.  A common cause of this is not having enough room
    available on the disk you are writing to.


WSSD: Processing terminated.

    A previously described error has caused WSSD to terminate
    processing without creating a complete Shorthand overlay
    file.





                            # # # # #